home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1994 March / Internet Info CD-ROM (Walnut Creek) (March 1994).iso / inet / ien / ien-164 < prev    next >
Text File  |  1988-12-01  |  40KB  |  1,416 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.                              CMOS SYSTEM OVERVIEW
  10.  
  11.  
  12.  
  13.                    Jerry Stern, Greg Ruth, and Jack Haverty
  14.  
  15.  
  16.                          Bolt Beranek and Newman Inc.
  17.  
  18.  
  19.                                January 12, 1981
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.        Stern, Ruth, and Haverty       -1-                    Version 1.0
  59.  
  60.        IEN 164                   January 1981               Preliminary
  61.  
  62.  
  63.  
  64.  
  65.                                Table of Contents
  66.  
  67.  
  68.  
  69.  
  70.        1   Introduction.......................................... 2
  71.        2   General Design Considerations......................... 3
  72.        3   Process Management.................................... 5
  73.        4   Interprocess Communication............................ 5
  74.        5   Input/Output.......................................... 6
  75.        6   Memory Allocation..................................... 7
  76.        7   System Clock.......................................... 8
  77.        8   Software Development Tools............................ 8
  78.        9   Future Development.................................... 8
  79.        10   CMOS System Calls.................................... 9
  80.        11   System Generation................................... 19
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.        Stern, Ruth, and Haverty       -i-                    Version 1.0
  118.  
  119.        IEN 164                   January 1981               Preliminary
  120.  
  121.  
  122.  
  123.  
  124.        1  Introduction
  125.  
  126.             CMOS is a multiprogrammed  real-time  operating  system  for
  127.        BBN's  C-machines.   It is essentially a reimplementation of MOS,
  128.        (1) a PDP-11 operating system developed by SRI.  Whereas  MOS  is
  129.        written in Macro-11 assembly language, CMOS is written in C.  (2)
  130.  
  131.             Programming  support  for  CMOS  is  provided  by  the  UNIX
  132.        operating  system.   CMOS  itself,  as  well  as  program modules
  133.        written to run as CMOS processes, are edited and compiled on  the
  134.        UNIX  operating  system,  and  object modules are loaded into the
  135.        target machine.  Since both the development and  target  machines
  136.        support  C-based  code,  it  is  also feasible to do some initial
  137.        debugging in the time-shared environment.
  138.  
  139.             CMOS is a small, simple operating system that  provides  the
  140.        following basic features:
  141.  
  142.                - multiple processes
  143.  
  144.                - interprocess communication/coordination
  145.  
  146.                - asynchronous I/O
  147.  
  148.                - memory allocation
  149.  
  150.                - system clock management.
  151.  
  152.  
  153.             CMOS development was motivated by the desire  to  produce  a
  154.        C-machine  operating  system  suitable for use in communications-
  155.        oriented applications.  In light  of  favorable  experience  with
  156.        MOS,  it was decided to adapt a version of MOS for the C-machine.
  157.        The choice of C as a system programming language was dictated  by
  158.        the  specific  nature  of  the  C-machine.   The  C-machine  is a
  159.        microprogrammed,  20-bit  machine  which  has   an   architecture
  160.        explicitly  designed  to  support  the C language.  The C-machine
  161.        comes in two models:  the C/50, which has a 1-megabyte (1  "byte"
  162.        =  10  bits) physical address space and no memory management; and
  163.        the C/70,  which  has  a  2-megabyte  address  space  and  memory
  164.        management.   Versions  of  CMOS  have been developed for both of
  165.        these machines, as well as for the LSI-11 and the Z8000.
  166.  
  167.  
  168.        _______________
  169.        (1) Kunzelman, R. C.,  J. E. Mathis,  and  D. L. Retz,  "Progress
  170.        Report  on Packet Radio Experimental Network, Quarterly Technical
  171.        Report No. 8."
  172.        (2)  Kernighan,  B.  W.  and  D.  M.  Ritchie, "The C Programming
  173.        Language", Prentice-Hall, Inc., 1978.
  174.  
  175.  
  176.        Stern, Ruth, and Haverty       -2-                    Version 1.0
  177.  
  178.        IEN 164                   January 1981               Preliminary
  179.  
  180.  
  181.  
  182.  
  183.             It should be noted that, although CMOS is targeted  for  use
  184.        in  several  applications,  it has not yet been used anywhere and
  185.        should be considered as still under development.
  186.  
  187.             One major motivation for the creation of CMOS was to provide
  188.        an  operating  system for the C machines, for use in applications
  189.        where the memory limitations make LSI-11  approaches  unsuitable.
  190.        Although  CMOS  will run on LSI-11s, this is not an intended use.
  191.        CMOS systems may use processes which exceed the address space  of
  192.        the  LSI-11  architecture,  and  can only be run on C-machines or
  193.        other machines which support the needed memory.
  194.  
  195.             The important aspects of the CMOS design  are  described  in
  196.        the  following  sections.   The final sections provide a detailed
  197.        description of CMOS  primitives  and  general  system  generation
  198.        information.
  199.  
  200.  
  201.  
  202.        2  General Design Considerations
  203.  
  204.             The design and programming of CMOS have  been  motivated  by
  205.        goals  of style, clarity, and consistency rather than a desire to
  206.        achieve ultimate efficiency.  This is not to say that  efficiency
  207.        issues have been ignored.  CMOS is quite compact and efficient by
  208.        virtue of its  simplicity.   Design  principles  and  programming
  209.        practices  have  not  been  compromised, however, for the sake of
  210.        saving every possible byte or cpu cycle.
  211.  
  212.             CMOS is designed to be an  "open"  operating  system.   This
  213.        means  that  no  distinct  division  exists between the operating
  214.        system and the application program.  One can view  the  operating
  215.        system as a collection of library routines.  The operating system
  216.        can be easily extended by adding new routines and can be  reduced
  217.        by  excluding  unneeded routines.  The programmer is not confined
  218.        to the outermost interface presented by the operating system.  If
  219.        appropriate,  the  programmer  can  directly  access  lower-level
  220.        interfaces.
  221.  
  222.             Although CMOS is intended primarily for  C-machines,  it  is
  223.        designed  to  be a portable operating system.  The use of a high-
  224.        level language is,  of  course,  the  principal  factor  in  CMOS
  225.        portability.   Small  size  and  simplicity  are  other important
  226.        factors.  The design attempts to minimize the amount of  machine-
  227.        dependent  code  and  to segregate it into separate modules.  The
  228.        I/O system design allows for easy replacement of device-dependent
  229.        modules.   Versions  of  CMOS  exist for the PDP-11 and the Z8000
  230.        computers.
  231.  
  232.  
  233.  
  234.  
  235.        Stern, Ruth, and Haverty       -3-                    Version 1.0
  236.  
  237.        IEN 164                   January 1981               Preliminary
  238.  
  239.  
  240.  
  241.  
  242.             CMOS does not  support  either  virtual  memory  or  virtual
  243.        address  spaces.   The  entire  system  shares a single, physical
  244.        address space.  This lack of  sophistication  is  due,  in  large
  245.        part, to the nature of real-time systems.  Programs and data must
  246.        be continuously  available  in  main  memory  in  order  to  meet
  247.        response-time requirements.  Thus, virtual memory techniques such
  248.        as  swapping  or  paging   are   not   suitable   for   real-time
  249.        applications.
  250.  
  251.             The issue of virtual address  spaces  is  more  complicated.
  252.        The  most  common  reason for providing virtual address spaces in
  253.        real-time systems is to overcome an architectural  deficiency  of
  254.        the  computer.  Many computers have small address spaces, yet can
  255.        support a much larger  amount  of  physical  memory.   Therefore,
  256.        multiple  address spaces are required to take advantage of larger
  257.        memory sizes.
  258.  
  259.             The C-machines do not suffer from this architectural defect.
  260.        The C/50 provides a one-megabyte address space and the C/70 twice
  261.        that.  This is  sufficient  for  all  currently  envisioned  CMOS
  262.        applications.   For  this reason, the current CMOS does not need,
  263.        and does not support, virtual address spaces.  For other machines
  264.        (e.g.,  the  PDP-11),  address space limitations are more severe.
  265.        On these machines, CMOS may be limited  to  a  class  of  smaller
  266.        applications.
  267.  
  268.             Other applications may motivate further extensions to  CMOS,
  269.        to  introduce  process  isolation  using  memory mapping, dynamic
  270.        process creation, preemption, or other  additions  to  the  basic
  271.        functionality.
  272.  
  273.             The use  of  a  single  address  space  gives  CMOS  several
  274.        important advantages over multiple address space systems.  First,
  275.        the single address space is a major contributing  factor  to  the
  276.        overall  simplicity  of  CMOS.   Not only is the operating system
  277.        relieved  of  address  space   management   chores,   but   also,
  278.        programming  and  debugging  are  generally facilitated.  Second,
  279.        data  sharing  among  processes  is   direct,   convenient,   and
  280.        efficient.   In multiple address space systems, memory sharing is
  281.        often a difficult problem.  Third, I/O devices have direct access
  282.        to all of memory.  In multiple address space systems, I/O devices
  283.        are typically restricted to a single address space.   This  often
  284.        produces  a need for extra data copying, especially in connection
  285.        with DMA devices.   Fourth,  an  entire  CMOS  system  is  linked
  286.        together as one composite program.  This means that non-identical
  287.        processes can still share a single copy  of  common  subroutines.
  288.        Multiple address space systems usually cannot match this level of
  289.        code-space efficiency.  The large address space provided by  CMOS
  290.        obviates  the need to artificially split systems into a number of
  291.  
  292.  
  293.  
  294.        Stern, Ruth, and Haverty       -4-                    Version 1.0
  295.  
  296.        IEN 164                   January 1981               Preliminary
  297.  
  298.  
  299.  
  300.  
  301.        processes because of the address space limitations.
  302.  
  303.  
  304.  
  305.        3  Process Management
  306.  
  307.             CMOS processes are defined at compilation time.  They cannot
  308.        be dynamically created or destroyed during system operation.  For
  309.        each process, a set of basic attributes is specified including  a
  310.        name, an initial program entrypoint, and a stack size.
  311.  
  312.             CMOS employs a rudimentary process scheduling method.  Three
  313.        process  states  are defined:  (1) running; (2) ready to run; and
  314.        (3) waiting for an event.   A  running  process  always  runs  to
  315.        completion.   This  means that the processor is relinquished only
  316.        by explicit action of the running process.   It  is  never  taken
  317.        away  by the operating system.  There is no time-slicing or other
  318.        form of preemption.  The next process to run  is  selected  by  a
  319.        simple  round-robin  algorithm.   All  processes  have  a uniform
  320.        scheduling priority.
  321.  
  322.             This  non-preemptive  scheduling  discipline  has  important
  323.        implications.    First,   processes   must  be  designed  not  to
  324.        monopolize the  processor  for  long  time  periods.   Otherwise,
  325.        crucial  tasks  may  fail  to  be  serviced  in a timely fashion.
  326.        Second, critical program sections (i.e.,  program  sections  that
  327.        can  be  safely  entered  by  only one process at a time) need no
  328.        explicit protection.  The absence of  preemption  guarantees  the
  329.        integrity of critical program sections.
  330.  
  331.             Interrupt handling creates  a  separate  class  of  critical
  332.        sections  that  are  not  protected by the scheduling discipline.
  333.        These critical sections exist only within  the  operating  system
  334.        and  are  of  no  concern to application programs.  CMOS protects
  335.        these  critical  sections  in  the  standard  manner  (viz.,   by
  336.        temporarily disabling interrupts).
  337.  
  338.  
  339.  
  340.        4  Interprocess Communication
  341.  
  342.             CMOS processes  communicate  with  one  another  by  passing
  343.        messages  known  as  "events".   For  this purpose, the operating
  344.        system provides primitives called "signal", "wait",  and  "recv".
  345.        The  signal  primitive  permits  a  process  to  send an event to
  346.        another process.  The wait primitive permits a  process  to  wait
  347.        for  an  event  that  may  or  may  not  have  arrived.  The recv
  348.        primitive permits a process to receive an event that has  already
  349.        arrived.
  350.  
  351.  
  352.  
  353.        Stern, Ruth, and Haverty       -5-                    Version 1.0
  354.  
  355.        IEN 164                   January 1981               Preliminary
  356.  
  357.  
  358.  
  359.  
  360.             An event message contains the sender process  ID,  an  event
  361.        ID,  and  one  word of unspecified data.  The event ID is used to
  362.        indicate the type of event.  Both the wait and receive primitives
  363.        allow  a  process  to select the event IDs of immediate interest.
  364.        The meaning of the data word depends on the event  type.   It  is
  365.        quite  common  for the data word to contain a pointer to a larger
  366.        data structure.
  367.  
  368.             CMOS provides  a  facility  that  helps  to  automate  event
  369.        processing activities.  A process can designate a procedure to be
  370.        the event handler for a particular event type.   Thereafter,  the
  371.        event  handler  becomes active whenever a special wait primitive,
  372.        called "waith", is  invoked.   For  each  event  received,  waith
  373.        checks  to  see if an event handler has been defined.  If so, the
  374.        event handler procedure is automatically dispatched.  This  frees
  375.        the  caller  of  waith  from the responsibility of having to deal
  376.        with events not of direct interest.  Processing of  these  events
  377.        can be viewed as a background activity.
  378.  
  379.  
  380.  
  381.        5  Input/Output
  382.  
  383.             CMOS provides an asynchronous I/O facility.  To perform I/O,
  384.        a  process  creates  an  I/O  request  block  (IORB).   The  IORB
  385.        identifies the target device, the type of operation (e.g.,  read,
  386.        write,   abort),  and  information  relevant  to  the  particular
  387.        operation (e.g., buffer areas for data transfer).  The IORB  also
  388.        specifies  an  event  ID.   To  initiate  processing, the IORB is
  389.        passed to the operating system.  When the request  is  completed,
  390.        the  operating system signals an event to the requesting process.
  391.        The event message contains the event ID taken from the IORB and a
  392.        data  word  that  contains the address of the IORB.  In this way,
  393.        the requesting process can easily associate the completion  event
  394.        with the original request.  Status information is returned in the
  395.        IORB.
  396.  
  397.             A process can direct I/O  to  a  specific  device  or  to  a
  398.        special  "primary" device.  Primary devices are defined on a per-
  399.        process basis and can be either assigned (to a  specific  device)
  400.        or  unassigned.   If  a  process  attempts  to  perform I/O on an
  401.        unassigned primary device,  the  process  is  suspended  until  a
  402.        primary  device  is assigned.  This permits a single device to be
  403.        moved from one process to another and thereby provides  a  simple
  404.        way to share a terminal among several processes.
  405.  
  406.             The core of the CMOS  I/O  system  is  a  device-independent
  407.        module,  "eior"  (enter I/O request), that provides a centralized
  408.        interface between the application program and the various  device
  409.        driver modules.  As described above, this interface accepts IORBs
  410.        from the application program.  The IORBs are automatically queued
  411.  
  412.        Stern, Ruth, and Haverty       -6-                    Version 1.0
  413.  
  414.        IEN 164                   January 1981               Preliminary
  415.  
  416.  
  417.  
  418.  
  419.        on  a  per-device  basis.   If  desired,  requests from different
  420.        processes can be interspersed for the same device.  When a device
  421.        becomes  ready  to accept the next request, the first IORB in the
  422.        device queue, if any, is passed to the appropriate device  driver
  423.        module.
  424.  
  425.             All device driver modules provide a  standardized  interface
  426.        expected by the core I/O system.  This interface consists of four
  427.        entrypoints:  (1) a configuration entry;  (2)  an  initialization
  428.        entry;  (3)  a request entry; and (4) an interrupt handler entry.
  429.        A system configuration table specifies the  driver  configuration
  430.        entry   for  each  device.   During  system  initialization,  the
  431.        configuration entry is invoked to obtain the other  three  driver
  432.        entrypoints, and the size of any per-device data base required by
  433.        the driver.  The initialization entry  is  invoked  automatically
  434.        before  the  first IORB is passed to the driver.  The request and
  435.        interrupt  handler  entries  perform  standard   device   control
  436.        functions.    At   present,  CMOS  includes  driver  modules  for
  437.        asynchronous terminals and for 1822 network interfaces.
  438.  
  439.  
  440.  
  441.        6  Memory Allocation
  442.  
  443.             CMOS includes routines that allocate and  deallocate  blocks
  444.        of  memory  from  a free storage pool.  Both the operating system
  445.        and  the  application  program  share  a  common   pool.    Three
  446.        allocation  options  are  available  to  control operating system
  447.        behavior in the case of an  allocation  failure:  (1)  return  an
  448.        error code; (2) wait for more memory to become available; and (3)
  449.        cease system operation.
  450.  
  451.             CMOS  provides  an  allocation  mechanism   only,   not   an
  452.        allocation  policy.  The policy, of course, is the responsibility
  453.        of  the  application  program.    In   practice,   however,   few
  454.        application  programs incorporate a memory allocation policy that
  455.        eliminates the possibility of free  space  exhaustion.   Instead,
  456.        some  applications include a recovery mechanism to deal with this
  457.        problem.  It is reasonable to expect that such a  mechanism  will
  458.        depend  upon  the  continued functioning of the operating system.
  459.        Therefore,  the  operating  system   must   not   itself   become
  460.        immediately disabled as a result of free space exhaustion.
  461.  
  462.             To prevent disablement, CMOS  depends  on  "reserve  storage
  463.        pools".  A separate reserve storage pool is created for each type
  464.        of object needed by a crucial  function.   The  operating  system
  465.        uses  two  such  pools,  one for event messages and one for timer
  466.        queue entries.  Reserve storage  pools  are  managed  by  special
  467.        allocation  and  deallocation  routines.   The special allocation
  468.        routine first attempts to obtain space from the common pool.   If
  469.        this  fails, space is taken instead from the reserve pool and the
  470.  
  471.        Stern, Ruth, and Haverty       -7-                    Version 1.0
  472.  
  473.        IEN 164                   January 1981               Preliminary
  474.  
  475.  
  476.  
  477.  
  478.        caller is so informed.  If the reserve  pool  is  exhausted,  the
  479.        system dies.
  480.  
  481.             System primitives that use reserve storage pools  return  an
  482.        indication   of   when  reserve  storage  has  been  tapped.   An
  483.        application program can therefore detect free space exhaustion by
  484.        this  means  or  by  the  direct  failure  of a simple allocation
  485.        request.  At this point, the operating system  will  continue  to
  486.        function  for a period of time (or number of calls) determined by
  487.        reserve storage pool sizes.
  488.  
  489.  
  490.  
  491.        7  System Clock
  492.  
  493.             CMOS provides a clock management facility that  maintains  a
  494.        time-of-day  clock  and  permits  processes  to set "alarms".  An
  495.        alarm is simply an event that is signalled by the  clock  manager
  496.        after a specified time period has elapsed.  Both the event ID and
  497.        the data word of the event message are specified by  the  process
  498.        that  sets the alarm.  An alarm can be either a one-time alarm or
  499.        an interval alarm  that  is  automatically  repeated  at  regular
  500.        intervals.
  501.  
  502.  
  503.  
  504.        8  Software Development Tools
  505.  
  506.             All programming support for CMOS software development is now
  507.        provided by the UNIX time-sharing system, via the UNIX C compiler
  508.        and linker.   BBN  has  developed  a  Version  7  UNIX  and  a  C
  509.        compiler/linker to run on the C-machines.
  510.  
  511.             The same hardware configuration of a C-machine  can  support
  512.        both  the  UNIX and CMOS systems, although not simultaneously, of
  513.        course.  We plan to use the  UNIX  system  development  tools  to
  514.        create  CMOS  systems,  which  can  then  be  run  and  tested by
  515.        bootstrapping the CMOS code in place  of  UNIX  on  the  same  or
  516.        different hardware.
  517.  
  518.  
  519.  
  520.        9  Future Development
  521.  
  522.             There is a variety of possible  extensions  to  CMOS,  which
  523.        take  advantage  of  the  increased  flexibility  provided by the
  524.        hardware  base.   We  intend  to   pursue   these   as   specific
  525.        applications arise which require additional functionality.
  526.  
  527.  
  528.  
  529.  
  530.        Stern, Ruth, and Haverty       -8-                    Version 1.0
  531.  
  532.        IEN 164                   January 1981               Preliminary
  533.  
  534.  
  535.  
  536.  
  537.             The most interesting category of extensions involves the use
  538.        of  the memory mapping hardware available for C machines.  In the
  539.        standard  C-machine  configuration,  the  20-bit  address   space
  540.        provides access to a physical memory of 1 Mbyte.
  541.  
  542.             Within this physical address space, processes can share  any
  543.        or  all  of the memory, since the process address space is also 1
  544.        Mbyte.
  545.  
  546.             The   memory   mapper   hardware   extends   the   machine's
  547.        capabilities  in  two  ways.   The  first  extension provides for
  548.        support of  2  Mbytes  of  physical  memory.   Each  process  is,
  549.        however,  limited  to  1  Mbyte  of  address  space.   The second
  550.        extension lies in the ability of the memory map to support  eight
  551.        independent  active process maps.  This creates an environment in
  552.        which processes can share portions of their address  spaces  with
  553.        the  system  or  other  processes,  with  fast  context switching
  554.        between the eight active processes.   This  removes  two  of  the
  555.        basic  limitations we have encountered in real-time designs based
  556.        on  PDP-11  architectures,  namely,  the  granularity  of  memory
  557.        sharing and the speed of context switching.
  558.  
  559.             The CMOS environment has not yet been  extended  to  utilize
  560.        these  additional  facilities,  although  we anticipate that this
  561.        effort will begin soon.
  562.  
  563.  
  564.  
  565.        10  CMOS System Calls
  566.  
  567.             This section describes CMOS system calls  available  to  the
  568.        application  programmer.   These calls are divided into two major
  569.        groups, low-level  functions  and  higher-level  functions.   The
  570.        low-level  functions correspond roughly to the MOS interface, and
  571.        the   higher-level   functions   provide    certain    additional
  572.        capabilities.   The  usage  of  each  system call is described in
  573.        terms of the C language.  Two typedefs are first defined and then
  574.        referenced by a few of the system call descriptions.
  575.  
  576.  
  577.  
  578.  
  579.        typedef struct {                /* event message buffer */
  580.                char msevent;           /* event ID */
  581.                char mssender;          /* sender process ID */
  582.                int msdata;             /* user data */
  583.        } MSG;
  584.  
  585.  
  586.  
  587.  
  588.  
  589.        Stern, Ruth, and Haverty       -9-                    Version 1.0
  590.  
  591.        IEN 164                   January 1981               Preliminary
  592.  
  593.  
  594.  
  595.  
  596.  
  597.        typedef struct iorb {           /* I/O request block */
  598.                struct iorb *irnextp;   /* ptr to next IORB on chain */
  599.                int irdevid;            /* device ID */
  600.                char irevent;           /* completion signal event */
  601.                char irpid;             /* requestor's process ID */
  602.                char *irbufp;           /* buffer ptr */
  603.                char irport;            /* port number of request */
  604.                char iropcode;          /* operation code */
  605.                int irbufsiz;           /* buffer size (in bytes) */
  606.                int irstatus;           /* status of I/O operation */
  607.                int irnxfer;            /* number of bytes transferred */
  608.                int irpad[2];           /* mysterious padding */
  609.        } IORB;
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.        Stern, Ruth, and Haverty      -10-                   Version 1.0
  649.  
  650.        IEN 164                   January 1981               Preliminary
  651.  
  652.  
  653.  
  654.  
  655.                               LOW-LEVEL FUNCTIONS
  656.  
  657.  
  658.  
  659.  
  660.        Process Attributes
  661.  
  662.  
  663.        Name:     getpid
  664.        Function: convert process name to process ID
  665.        Usage:    pid = getpid (name)
  666.  
  667.                  char name[];  /* process name to convert
  668.                                   null name => calling process */
  669.                  int pid;      /* process ID for given name */
  670.  
  671.  
  672.  
  673.  
  674.        Name:     getpn
  675.        Function: convert process ID to process name
  676.        Usage:    pn = getpn (pid, namep)
  677.  
  678.                  int pid;      /* process ID to convert
  679.                                   0 => calling process */
  680.                  char *namep;  /* place to store name */
  681.                  char *pn;     /* same as namep */
  682.  
  683.  
  684.  
  685.  
  686.        Name:     getprio
  687.        Function: get primary I/O devices of specified process
  688.        Usage:    getprio (pid, priop)
  689.  
  690.                  int pid;      /* process ID, 0 => calling process */
  691.                  struct {
  692.                   int idevid;  /* primary input device ID */
  693.                   int odevid;  /* primary output device ID */
  694.                  } *priop;
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.        Stern, Ruth, and Haverty      -11-                   Version 1.0
  708.  
  709.        IEN 164                   January 1981               Preliminary
  710.  
  711.  
  712.  
  713.  
  714.  
  715.        Name:     setprio
  716.        Function: set primary I/O devices of specified process
  717.        Usage:    setprio (pid, idevid, odevid)
  718.  
  719.                  int pid;      /* process ID, 0 => calling process */
  720.                  int idevid;   /* input device ID, <0 => no change */
  721.                  int odevid;   /* output device ID, <0 => no change */
  722.  
  723.  
  724.  
  725.  
  726.        Name:     movprio
  727.        Function: move primary I/O devices of caller to another process
  728.        Usage:    movprio (pid)
  729.  
  730.                  int pid;      /* target process ID */
  731.  
  732.  
  733.  
  734.  
  735.  
  736.        Device Attributes
  737.  
  738.  
  739.        Name:     getdid
  740.        Function: convert device name to device ID
  741.        Usage:    devid = getdid (name)
  742.  
  743.                  char name[];  /* device name to convert */
  744.                  int devid;    /* device ID */
  745.  
  746.  
  747.  
  748.  
  749.        Name:     getdn
  750.        Function: convert device ID to device name
  751.        Usage:    dn = getdn (devid, namep)
  752.  
  753.                  int devid;    /* device ID to convert */
  754.                  char *namep;  /* place to store name */
  755.                  char *dn;     /* same as namep */
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.        Stern, Ruth, and Haverty      -12-                   Version 1.0
  767.  
  768.        IEN 164                   January 1981               Preliminary
  769.  
  770.  
  771.  
  772.  
  773.  
  774.        Input/Output
  775.  
  776.  
  777.        Name:     eior
  778.        Function: enter an I/O request
  779.        Usage:    ec = eior (iorbp)
  780.  
  781.                  IORB *iorbp;  /* I/O request block ptr */
  782.                  int ec;       /* error code */
  783.  
  784.  
  785.  
  786.  
  787.  
  788.        Interprocess Communication
  789.  
  790.  
  791.        Name:     signal
  792.        Function: signal an event to a process
  793.        Usage:    sw = signal (pid, event, data)
  794.  
  795.                  char pid;     /* target process  ID */
  796.                  char event;   /* event number */
  797.                  int data;     /* data for target process */
  798.                  int sw;       /* 1 if reserve pool used to queue
  799.                                   signal, else 0 */
  800.  
  801.  
  802.  
  803.  
  804.        Name:     wait
  805.        Function: wait for any event
  806.        Usage:    wait (msgp)
  807.  
  808.                  MSG *msgp;    /* ptr to message buffer */
  809.  
  810.  
  811.  
  812.  
  813.        Name:     waits
  814.        Function: wait for a single specified event
  815.        Usage:    waits (event, msgp)
  816.  
  817.                  char event;   /* desired event */
  818.                  MSG *msgp;    /* message buffer ptr */
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.        Stern, Ruth, and Haverty      -13-                   Version 1.0
  826.  
  827.        IEN 164                   January 1981               Preliminary
  828.  
  829.  
  830.  
  831.  
  832.  
  833.        Name:     waitm
  834.        Function: wait for one of multiple specified events
  835.        Usage:    waitm (evlist, nev, msgp);
  836.  
  837.                  char *evlist; /* event list (array) */
  838.                  int nev;      /* number of events in list */
  839.                  MSG *msgp;    /* message buffer ptr */
  840.  
  841.  
  842.  
  843.  
  844.        Name:     recv
  845.        Function: receive any pending event
  846.        Usage:    sw = recv (msgp)
  847.  
  848.                  MSG *msgp;    /* ptr to message buffer */
  849.                  int sw;       /* 1 if event returned, else 0 */
  850.  
  851.  
  852.  
  853.  
  854.        Name:     recvs
  855.        Function: receive a single specified pending event
  856.        Usage:    sw = recvs (event, msgp)
  857.  
  858.                  char event;   /* desired event */
  859.                  MSG *msgp;    /* message buffer ptr */
  860.                  int sw;       /* 1 if event returned, else 0 */
  861.  
  862.  
  863.  
  864.  
  865.        Name:     recvm
  866.        Function: receive one of multiple specified pending events
  867.        Usage:    sw = recvm (evlist, nev, msgp);
  868.  
  869.                  char *evlist; /* event list (array) */
  870.                  int nev;      /* number of events in list */
  871.                  MSG *msgp;    /* message buffer ptr */
  872.                  int sw;       /* 1 if event returned, else 0 */
  873.  
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.        Stern, Ruth, and Haverty      -14-                   Version 1.0
  885.  
  886.        IEN 164                   January 1981               Preliminary
  887.  
  888.  
  889.  
  890.  
  891.  
  892.        Memory Allocation
  893.  
  894.  
  895.        Name:     alloc
  896.        Function: allocate memory block, return if not available
  897.        Usage:    blkp = alloc (nbytes)
  898.  
  899.                  int nbytes;   /* size of block desired */
  900.                  char *blkp;   /* ptr to allocated block, else null */
  901.  
  902.  
  903.  
  904.  
  905.        Name:     allocw
  906.        Function: allocate memory block, wait if not available
  907.        Usage:    blkp = allocw (nbytes)
  908.  
  909.                  int nbytes;   /* size of block desired */
  910.                  char *blkp;   /* ptr to allocated block */
  911.  
  912.  
  913.  
  914.  
  915.        Name:     allocd
  916.        Function: allocate memory block, die if not available
  917.        Usage:    blkp = allocd (nbytes)
  918.  
  919.                  int nbytes;   /* size of block desired */
  920.                  char *blkp;   /* ptr to allocated block */
  921.  
  922.  
  923.  
  924.  
  925.        Name:     free
  926.        Function: free a previously allocated block
  927.        Usage:    free (blkp)
  928.  
  929.                  char *blkp;   /* ptr to block */
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.        Stern, Ruth, and Haverty      -15-                   Version 1.0
  944.  
  945.        IEN 164                   January 1981               Preliminary
  946.  
  947.  
  948.  
  949.  
  950.  
  951.        System Clock Management
  952.  
  953.  
  954.        Name:     alarm
  955.        Function: set alarm to awaken process
  956.        Usage:    sw = alarm (event, data, delay)
  957.  
  958.                  char event;   /* signal event */
  959.                  int data;     /* signal data */
  960.                  int delay;    /* timeout period in seconds/60 */
  961.                  int sw;       /* 1 if reserve pool used to queue
  962.  
  963.  
  964.  
  965.  
  966.        Name:     ialarm
  967.        Function: set alarm to awaken process at regular intervals
  968.        Usage:    sw = ialarm (event, data, interval)
  969.  
  970.                  char event;   /* signal event */
  971.                  int data;     /* signal data */
  972.                  int interval; /* timeout interval in seconds/60 */
  973.                  int sw;       /* 1 if reserve pool used to queue
  974.  
  975.  
  976.  
  977.  
  978.        Name:     kalarm
  979.        Function: kill any specified pending alarms
  980.        Usage:    kalarm (event, data)
  981.  
  982.                  char event;   /* event of requests to kill */
  983.                  int data;     /* data of requests to kill */
  984.  
  985.  
  986.  
  987.  
  988.        Name:     setod
  989.        Function: set time of day
  990.        Usage:    setod (time)
  991.  
  992.                  long time;    /* time of day */
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.  
  1000.  
  1001.  
  1002.        Stern, Ruth, and Haverty      -16-                   Version 1.0
  1003.  
  1004.        IEN 164                   January 1981               Preliminary
  1005.  
  1006.  
  1007.  
  1008.  
  1009.  
  1010.        Name:     getod
  1011.        Function: get time of day
  1012.        Usage:    time = getod ()
  1013.  
  1014.                  long time;    /* time of day */
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  
  1021.  
  1022.  
  1023.  
  1024.  
  1025.  
  1026.  
  1027.  
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.        Stern, Ruth, and Haverty      -17-                   Version 1.0
  1062.  
  1063.        IEN 164                   January 1981               Preliminary
  1064.  
  1065.  
  1066.  
  1067.  
  1068.                             HIGHER-LEVEL FUNCTIONS
  1069.  
  1070.  
  1071.  
  1072.  
  1073.        Event Management
  1074.  
  1075.  
  1076.        Name:     newev
  1077.        Function: generate a new event number, unique system-wide
  1078.        Usage:    event = newev ()
  1079.  
  1080.                  char event;   /* event number */
  1081.  
  1082.  
  1083.  
  1084.  
  1085.        Name:     setevh
  1086.        Function: associate an event handler routine with a specified
  1087.                  event for this process
  1088.        Usage:    oldent = setevh (event, entryp)
  1089.  
  1090.                  char event;   /* event to be handled */
  1091.                  int (*entryp) (); /* event handler entrypoint */
  1092.                                /* if null, cancel event handler */
  1093.                  int (*oldent) (); /* previous entryp, else null */
  1094.  
  1095.  
  1096.  
  1097.  
  1098.        Name:     waith
  1099.        Function: wait for an event; dispatch event handler if one
  1100.                  is defined, else return.
  1101.        Usage:    waith (msgp)
  1102.  
  1103.                  MSG *msgp;    /* ptr to message buffer */
  1104.  
  1105.  
  1106.  
  1107.  
  1108.        Name:     waitsh
  1109.        Function: wait for an event; dispatch event handler if one is
  1110.                  defined; else return if event is the one specified;
  1111.                  else ignore event;
  1112.        Usage:    waitsh (event, msgp)
  1113.  
  1114.                  char event;   /* desired event */
  1115.                  MSG *msgp;    /* message buffer ptr */
  1116.  
  1117.  
  1118.  
  1119.  
  1120.        Stern, Ruth, and Haverty      -18-                   Version 1.0
  1121.  
  1122.        IEN 164                   January 1981               Preliminary
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.        Synchronous Input/Output
  1129.  
  1130.  
  1131.        Name:     read
  1132.        Function: read from a specified device; event handlers are
  1133.                  active while awaiting read completion.
  1134.        Usage:    nbytes = read (devid, bufp, bufsiz)
  1135.  
  1136.                  int devid;    /* device ID */
  1137.                  char *bufp;   /* buffer ptr */
  1138.                  int bufsiz;   /* buffer size */
  1139.                  int nbytes;   /* number of bytes read */
  1140.  
  1141.  
  1142.  
  1143.  
  1144.        Name:     write
  1145.        Function: write to a specified device; event handlers are
  1146.                  NOT active while awaiting write completion.
  1147.        Usage:    nbytes = write (devid, bufp, bufsiz)
  1148.  
  1149.                  int devid;    /* device ID */
  1150.                  char *bufp;   /* buffer ptr */
  1151.                  int bufsiz;   /* buffer size */
  1152.                  int nbytes;   /* number of bytes written */
  1153.  
  1154.  
  1155.  
  1156.  
  1157.        11  System Generation
  1158.  
  1159.             The following CMOS modules must be linked  into  any  system
  1160.        configuration:
  1161.  
  1162.             cm_init         Initialization routines.
  1163.  
  1164.             cm_data         Process control and configuration tables.
  1165.  
  1166.             cm_util         CMOS utilities.
  1167.  
  1168.             cm_err          Error message routines.
  1169.  
  1170.             cm_proc         Basic process management routines.
  1171.  
  1172.             cm_queue        Queue manipulation routines.
  1173.  
  1174.             cm_ipc          Interprocess communication routines.
  1175.  
  1176.             cm_mem          Memory management primitives.
  1177.  
  1178.  
  1179.        Stern, Ruth, and Haverty      -19-                   Version 1.0
  1180.  
  1181.        IEN 164                   January 1981               Preliminary
  1182.  
  1183.  
  1184.  
  1185.  
  1186.             cm_io           Basic I/O routines.
  1187.  
  1188.        In addition to  the  required  modules,  the  following  optional
  1189.        modules may be included for specific hardware device support:
  1190.  
  1191.             cm_time         Timer management routines.
  1192.  
  1193.             cm_tty          Terminal driver routines (to be rewritten).
  1194.  
  1195.             cm_1822         1822 driver routines (to be written).
  1196.  
  1197.             cm_smd          Disk driver routines (to be written).
  1198.  
  1199.             cm_mlc          MLC driver routines (to be written).
  1200.  
  1201.        In order to include DDT the following modules must be included:
  1202.  
  1203.             ddt_main
  1204.  
  1205.             ddt_cmd
  1206.  
  1207.             ddt_code
  1208.  
  1209.             ddt_brk
  1210.  
  1211.             ddt_sym
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  
  1225.  
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.        Stern, Ruth, and Haverty      -20-                   Version 1.0
  1239.  
  1240.        IEN 164                   January 1981               Preliminary
  1241.  
  1242.  
  1243.  
  1244.  
  1245.                                   References
  1246.  
  1247.  
  1248.  
  1249.        1. Mathis, J. and  Klemba,  K.,  "The  Micro  Operating  System,"
  1250.        Chapter  6  of  Terminal  Interface  Unit  Notebook,  Vol. 2, SRI
  1251.        International, March 1980.  <MOS reference>
  1252.  
  1253.        2.  Kraley,  M.  et  al.,  "Design  of  a  User-microprogrammable
  1254.        Building  Block," Thirteenth Annual Workshop on Microprogramming,
  1255.        Colorado Springs, Colorado, 1980.
  1256.  
  1257.        3.  Ritchie,  D.M.  and  Thompson,  K.,  "The  UNIX  Time-Sharing
  1258.        System,"  Bell  System  Technical  Journal  57(6)  pp.  1905-1929
  1259.        (1978).
  1260.  
  1261.        4. Kernighan, B.W. and Ritchie, D.M., The C Programming Language,
  1262.        Prentice-Hall, Inc., 1978.
  1263.  
  1264.  
  1265.  
  1266.  
  1267.  
  1268.  
  1269.  
  1270.  
  1271.  
  1272.  
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.        Stern, Ruth, and Haverty      -21-                   Version 1.0
  1298.  
  1299.        IEN 164                   January 1981               Preliminary
  1300.  
  1301.  
  1302.  
  1303.  
  1304.                                    APPENDIX
  1305.  
  1306.                     CMOS Error Messages (C-machine version)
  1307.  
  1308.  
  1309.        cvdevnm: Device not found
  1310.  
  1311.             The mate specified for a device (in the device control table
  1312.             initialization data) is not the name of any existing device.
  1313.  
  1314.  
  1315.        getdcte: Bad device ID
  1316.  
  1317.             The CMOS primitive (e.g. eior, getdn)  was  called  with  an
  1318.             invalid device id.
  1319.  
  1320.  
  1321.        dlvrmsg: NULL msg ptr
  1322.  
  1323.             Due to an internal error (blush).
  1324.  
  1325.  
  1326.        mkroom: Memory full
  1327.  
  1328.             Insufficient space in the free memory  pool  to  accommodate
  1329.             device  driver  data  and/or  process  stacks  during system
  1330.             initialization.
  1331.  
  1332.  
  1333.        alloc: Invalid request
  1334.  
  1335.             The CMOS primitive "alloc" has been called with  a  negative
  1336.             block size.
  1337.  
  1338.  
  1339.        free: Invalid addr
  1340.  
  1341.             The CMOS primitive "free" has been  called  with  a  pointer
  1342.             outside the free memory pool.
  1343.  
  1344.  
  1345.        allocd: Allocation failed
  1346.  
  1347.             An allocation request via the CMOS  primitive  "allocd"  has
  1348.             failed.
  1349.  
  1350.  
  1351.        plalloc: Pool empty
  1352.  
  1353.             The reserve memory pool has been exhausted.
  1354.  
  1355.  
  1356.        Stern, Ruth, and Haverty      -22-                   Version 1.0
  1357.  
  1358.        IEN 164                   January 1981               Preliminary
  1359.  
  1360.  
  1361.  
  1362.  
  1363.        dschd: Stack overflow
  1364.  
  1365.             A process has overrun its stack.  This  may  be  due  to  an
  1366.             excessive   depth  of  nested  procedure  calls.   The  only
  1367.             solution is to reassemble the system with more stack space.
  1368.  
  1369.  
  1370.        getpcte: Bad pid
  1371.  
  1372.             A CMOS primitive was called with a non-existent process id.
  1373.  
  1374.  
  1375.        mktqe: Bad delay time
  1376.  
  1377.             A CMOS clock management primitive was given a timeout period
  1378.             of 0 by the caller.
  1379.  
  1380.  
  1381.  
  1382.        In addition, there are various fatal conditions trapped by CMOS:
  1383.  
  1384.             TRAP: invalid memory addr
  1385.  
  1386.             TRAP: illegal instruction
  1387.  
  1388.             TRAP: illegal micro call
  1389.  
  1390.             TRAP: privileged operation
  1391.  
  1392.             TRAP: register overflow
  1393.  
  1394.             TRAP: EDAC error
  1395.  
  1396.             TRAP: register underflow
  1397.  
  1398.        For every trap the following machine status  values  are  printed
  1399.        out:
  1400.  
  1401.             PC = program counter
  1402.  
  1403.             PS = program status
  1404.  
  1405.             SP = stack pointer
  1406.  
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.  
  1415.        Stern, Ruth, and Haverty      -23-                   Version 1.0
  1416.